home *** CD-ROM | disk | FTP | other *** search
/ BCI NET 2 / BCI NET 2.iso / archives / programming / source / cardpkg_1.3.lha / CardPkg / Cards.doc < prev    next >
Encoding:
Text File  |  1994-11-21  |  14.7 KB  |  596 lines
  1.  
  2.  
  3.         TML's C Language Card Image Package v1.3               Page 1 of 9
  4.  
  5.  
  6.         Todd M. Lewis                                   Todd_Lewis@unc.edu
  7.         2601 Piedmont Drive                                 (919) 776-7386
  8.         Sanford, NC 27330-9437
  9.         USA
  10.  
  11.         The Card Package contains C source code for incorporating playing
  12.         card images into Intuition programs.  Three complete sets of card
  13.         images are provided.  One set has horizontal cards, the others have
  14.         vertical cards.  Though some are small (they were designed so that
  15.         52 cards could be shown at the same time on a Workbench screen),
  16.         attention to detail has not been spared.  All the face cards are
  17.         unique.  The Jack of Spades, the Jack of Hearts, and the King of
  18.         Diamonds are all "one-eyed" like they are supposed to be.  A joker
  19.         image is included, as well as the images of the back of a card, a
  20.         blank card, and black card image.
  21.  
  22.         The programming interface is straight-forward.  No initialization
  23.         is necessary (except for opening the intuition.library and the
  24.         graphics.library).  A blind type is defined (CardID_t) for
  25.         representing cards.  Four suits are defined for "normal" cards
  26.         (SUIT_SPADES, SUIT_HEARTS, SUIT_CLUBS, and SUIT_DIAMONDS) plus an
  27.         additional suit for the special images (SUIT_SPECIAL).  Functions
  28.         are provided for translating a (suit,rank) pair to a CardID
  29.         (CardID()) and back (CardSuit() and CardRank()).  These functions
  30.         provide error checking for invalid CardIDs and impossible
  31.         (suit,rank) combinations.  Functions are provided to initialize
  32.         (CardRange()) and shuffle (Shuffle()) an array of CardIDs.  Cards
  33.         are displayed by calling ShowVCard(), ShowHCard() or
  34.         ShowVBigCard().  Defined constants give the width and height of
  35.         both the horizontal and vertical card images.
  36.  
  37.         COLORS
  38.  
  39.         The cards were designed to work on a Workbench screen.  Under
  40.         system version 34 and before, the Workbench colors were Blue (or
  41.         something neutral), White, Black, and Orange (or some highlight
  42.         color).  Starting with version 35, White and Black were reversed.
  43.         The display routines notice which version of the system is being
  44.         used and exchange Black and White in the card images so that White
  45.         cards with Black edges are displayed.  If you use these images on a
  46.         custom screen where you have control over the palette, you may
  47.         defeat this color-swapping feature.  To defeat color-swapping, set
  48.         the extern BOOL CardColorSwapping to FALSE before ShowVCard() or
  49.         ShowHCard() is called the first time.
  50.  
  51.         The cards were designed with the following color palette:
  52.                Pen   |   Red   Green   Blue
  53.                  0   |     0       4     12     Blue
  54.                  1   |     0       0      0     Black
  55.                  2   |    14      12     10     Creamy White
  56.                  3   |    15       8      0     Rusty Red
  57.  
  58.  
  59.  
  60.  
  61.  
  62.  
  63.  
  64.                       * * * * * * * * * * * * * * * * * * * * * *
  65.  
  66.  
  67.  
  68.  
  69.         TML's C Language Card Image Package v1.3               Page 2 of 9
  70.  
  71.  
  72.  
  73.  
  74.         The following diagram shows the relationships between the different
  75.         files in the card package.
  76.  
  77.                                      Cards.h       The "?" is one of
  78.                                     /   |          "V", "H", or "VBig"
  79.                                    /    |
  80.                                   /     |          It is possible to
  81.         Card?Brush.c  Card?Images.h     |          use any combination
  82.                \        /      \        |          of the three card sets
  83.                 \      /        \       |          in a single program.
  84.                  \    /          \      |
  85.                Card?Images.c      \..Cards.c
  86.                    :             : \
  87.                    :            :   \
  88.                    :           :     \
  89.                    :          :     your_pgm.c
  90.                    :         :          :
  91.                    :         :          :
  92.             Card?Images.o  Cards.o  your_pgm.o
  93.  
  94.  
  95.         Solid lines ("\" and "/") represent file inclusions.  Dotted lines
  96.         (":") represent compile steps.  The xxxVxxx.y and xxxVBigxxx.y
  97.         files are for vertical card images, while the xxxHxxx.y files are
  98.         for horizontal card images.  You may use both sets or just one.  In
  99.         either case, you will need the Card.{h|o} files.
  100.  
  101.         The Card?Brush.c files are kept separate from the Card?Images.c
  102.         files because they are produced from DPaint brushes by the ILBMtoC
  103.         program and filtered through the TrimLine program whenever the
  104.         brushes are modified.  (See the Makefile for the dependancy
  105.         relationships.)
  106.  
  107.         Other files/programs included with this distribution are:
  108.  
  109.           SMakefile     For the SAS/C compiler/linker (v6.51).
  110.           makefile      For the Aztec C compiler/linker (v5.2a).
  111.           CardVBrush
  112.           CardVBigBrush
  113.           CardHBrush    The DPaint brushes for the cards.
  114.           TrimLine.c    (pgm) Shortens text lines of C source files.
  115.           Hello_V.c
  116.           Hello_H.c     Example source code using the card package.
  117.           Hello_V       (pgm)
  118.           Hello_H       (pgm) Executable examples.
  119.           Cards.doc     This file.
  120.  
  121.         If you modify CardVBrush or CardHBrush you will need the program
  122.         ILBMtoC (from the Commodore IFF distributions) or an equivalent
  123.         program to convert an IFF ILBM brush to C source code.
  124.  
  125.  
  126.  
  127.  
  128.  
  129.  
  130.                       * * * * * * * * * * * * * * * * * * * * * *
  131.  
  132.  
  133.  
  134.  
  135.         TML's C Language Card Image Package v1.3               Page 3 of 9
  136.  
  137.  
  138.         NAME
  139.  
  140.           CardID -- Produce a CardID_t for a card of given suit and rank.
  141.  
  142.         SYNOPSIS
  143.  
  144.           card = CardID( Suit, Rank );
  145.  
  146.           CardID_t CardID( UWORD, UWORD );
  147.  
  148.         FUNCTION
  149.  
  150.           Produces the CardID_t for a given (suit,rank) pair.  Though in
  151.           general CardID_t is supposed to be a blind type, the relational
  152.           operators >, >=, <, <=, ==, != can be used to compare them with
  153.           each other.  In particular the CardID_t for any Spade < any Heart
  154.           < any Club < any Diamond < any Special.  Within a normal suit the
  155.           CardID_t for an Ace < Deuce < Tray < ... < Jack < Queen < King.
  156.           Within SUIT_SPECIAL the CardID_t for CARD_JOKER < CARD_BLANK <
  157.           CARD_BACK < CARD_BLACK.
  158.  
  159.         INPUTS
  160.  
  161.           Suit      One of the defined suits SUIT_SPADES, SUIT_HEARTS,
  162.                     SUIT_CLUBS, SUIT_DIAMONDS, or SUIT_SPECIAL.
  163.           Rank      The rank of the card.  Ace = 1, Queen = 12, etc.  For
  164.                     "normal" suits, valid ranks range from 1 to 13.  For
  165.                     cards of SUIT_SPECIAL the valid ranks are 1 through 4
  166.                     which result in CardID_t's of CARD_JOKER, CARD_BLANK,
  167.                     CARD_BACK, and CARD_BLACK.
  168.  
  169.         RESULT
  170.  
  171.           card = the new CardID_t or 0 (FALSE) if an invalid card was
  172.           specified.
  173.  
  174.         EXAMPLE
  175.  
  176.         NOTES
  177.  
  178.         BUGS
  179.  
  180.         SEE ALSO
  181.  
  182.  
  183.  
  184.  
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195.  
  196.                       * * * * * * * * * * * * * * * * * * * * * *
  197.  
  198.  
  199.  
  200.  
  201.         TML's C Language Card Image Package v1.3               Page 4 of 9
  202.  
  203.  
  204.         NAME
  205.  
  206.           CardRange -- Fill an array of CardID_t with requested CardIDs.
  207.  
  208.         SYNOPSIS
  209.  
  210.           success = CardRange( where, count, offset, firstSuit, firstRank);
  211.  
  212.           BOOL CardRange( CardID_t *, UWORD, UWORD, UWORD, UWORD);
  213.  
  214.         FUNCTION
  215.  
  216.           Fills an array with CardID_t's for cards in a selected range.  A
  217.           "normal" use would be to fill an array of 52 CardID_t's starting
  218.           with the Ace of Spades, but you could ask for a smaller range.
  219.           The "normal" suits (not SUIT_SPECIAL) wrap around, i.e., if you
  220.           ask for more cards than are in a given suit, the additional cards
  221.           come from the next suit.  You could ask for 104 cards if you
  222.           needed two full decks worth of cards.  The SUIT_SPECIAL cards do
  223.           not wrap around to other suits.
  224.  
  225.         INPUTS
  226.  
  227.           where     A pointer to the first CardID_t.
  228.           count     The number of CardID_t's to place into the array
  229.                     pointed to by where.
  230.           offset    The number of bytes from one CardID_t to the next.
  231.           firstSuit The suit to start filling the array with.  Once that
  232.                     suit is exhausted, the next suit is used, then the
  233.                     next, etc., until count CardIDs are placed.  If
  234.                     firstSuit is SUIT_SPECIAL, the suit doesn't change.
  235.           firstRank The face value of the first card.  The rank for
  236.                     subsequent cards is incremented for each card until a
  237.                     suit is exhausted, then it starts over again at Ace of
  238.                     the next suit.
  239.  
  240.         RESULT
  241.  
  242.           success = TRUE unless the suit/rank combination represents an
  243.           invalid card in which case success = FALSE.
  244.  
  245.         EXAMPLE
  246.  
  247.           typedef struct { int flag; CardID_t card } flagcard_t;
  248.           flagcard_t deck[ DECKSIZE ];
  249.                                           /* Fill a "normal" deck. */
  250.           success = CardRange( &deck[0].card, 52, sizeof(flagcard_t),
  251.                                                      SUIT_FIRST, 1 );
  252.         NOTES
  253.  
  254.         BUGS
  255.  
  256.         SEE ALSO
  257.  
  258.           Shuffle()
  259.  
  260.  
  261.  
  262.                       * * * * * * * * * * * * * * * * * * * * * *
  263.  
  264.  
  265.  
  266.  
  267.         TML's C Language Card Image Package v1.3               Page 5 of 9
  268.  
  269.  
  270.         NAME
  271.  
  272.           CardRank -- Find the rank of a given card.
  273.  
  274.         SYNOPSIS
  275.  
  276.           rank = CardRank( CardID );
  277.  
  278.           UWORD CardRank( CardID_t );
  279.  
  280.         FUNCTION
  281.  
  282.           Determines the rank of a given card.
  283.  
  284.         INPUTS
  285.  
  286.           CardID    A CardID_t which represents some card.
  287.  
  288.         RESULT
  289.  
  290.           rank = some value from 1 to 13 for all suits except SUIT_SPECIAL.
  291.           For SUIT_SPECIAL it returns 1 through 4 for the inputs
  292.           CARD_JOKER, CARD_BLANK, CARD_BACK, or CARD_BLACK respectively.
  293.           If CardID is invalid, CardRank() returns zero.
  294.  
  295.         EXAMPLE
  296.  
  297.         NOTES
  298.  
  299.         BUGS
  300.  
  301.         SEE ALSO
  302.  
  303.           CardSuit()
  304.  
  305.  
  306.  
  307.  
  308.  
  309.  
  310.  
  311.  
  312.  
  313.  
  314.  
  315.  
  316.  
  317.  
  318.  
  319.  
  320.  
  321.  
  322.  
  323.  
  324.  
  325.  
  326.  
  327.  
  328.                       * * * * * * * * * * * * * * * * * * * * * *
  329.  
  330.  
  331.  
  332.  
  333.         TML's C Language Card Image Package v1.3               Page 6 of 9
  334.  
  335.  
  336.         NAME
  337.  
  338.           CardSuit -- Find the suit of a given CardID.
  339.  
  340.         SYNOPSIS
  341.  
  342.           suit = CardSuit( CardID );
  343.  
  344.           UWORD CardSuit( CardID_t );
  345.  
  346.         FUNCTION
  347.  
  348.           Find the suit a given card belongs to.
  349.  
  350.         INPUTS
  351.  
  352.           CardID    A CardID_t which represents some card.
  353.  
  354.         RESULT
  355.  
  356.           Returns one of SUIT_SPADES, SUIT_HEARTS, SUIT_CLUBS,
  357.           SUIT_DIAMONDS, or SUIT_SPECIAL for valid CardIDs, or returns zero
  358.           if CardID is invalid.
  359.  
  360.         EXAMPLE
  361.  
  362.         NOTES
  363.  
  364.         BUGS
  365.  
  366.         SEE ALSO
  367.  
  368.           CardRank()
  369.  
  370.  
  371.  
  372.  
  373.  
  374.  
  375.  
  376.  
  377.  
  378.  
  379.  
  380.  
  381.  
  382.  
  383.  
  384.  
  385.  
  386.  
  387.  
  388.  
  389.  
  390.  
  391.  
  392.  
  393.  
  394.                       * * * * * * * * * * * * * * * * * * * * * *
  395.  
  396.  
  397.  
  398.  
  399.         TML's C Language Card Image Package v1.3               Page 7 of 9
  400.  
  401.  
  402.         NAME
  403.  
  404.           ShowHCard -- display a horizontal card.
  405.           ShowVCard,
  406.           ShowVBigCard -- display a vertical card.
  407.  
  408.         SYNOPSIS
  409.  
  410.           success = ShowHCard(    rp, cardid, dx, dy);
  411.           success = ShowVCard(    rp, cardid, dx, dy);
  412.           success = ShowVBigCard( rp, cardid, dx, dy);
  413.  
  414.           BOOL ShowHCard(    struct RastPort *, CardID_t, WORD, WORD );
  415.           BOOL ShowVCard(    struct RastPort *, CardID_t, WORD, WORD );
  416.           BOOL ShowVBigCard( struct RastPort *, CardID_t, WORD, WORD );
  417.  
  418.         FUNCTION
  419.  
  420.           Display the requested card in a RastPort.  The graphics.library
  421.           function BlitMaskBitMapRastPort() is used to copy the image, so
  422.           whatever caveats apply there apply here as well.
  423.  
  424.         INPUTS
  425.  
  426.           rp        A pointer to a valid struct RastPort.
  427.           cardid    A CardID for some card in the card package.  The
  428.                     special value CARD_NONE can also be used in which case
  429.                     the rectangle containing the card is cleared.
  430.           dx, dy    The coordinate for the upper left corner of the card.
  431.                     The dimensions of the cards are CARD_H_WIDTH by
  432.                     CARD_H_HEIGHT pixels for the horizontal cards, and
  433.                     CARD_V_WIDTH by CARD_V_HEIGHT pixels for the vertical
  434.                     cards.
  435.  
  436.         RESULT
  437.  
  438.           success = TRUE if CardID represents a valid card, FALSE
  439.           otherwise.
  440.  
  441.         EXAMPLE
  442.  
  443.         NOTES
  444.  
  445.         BUGS
  446.  
  447.         SEE ALSO
  448.  
  449.  
  450.  
  451.  
  452.  
  453.  
  454.  
  455.  
  456.  
  457.  
  458.  
  459.  
  460.                       * * * * * * * * * * * * * * * * * * * * * *
  461.  
  462.  
  463.  
  464.  
  465.         TML's C Language Card Image Package v1.3               Page 8 of 9
  466.  
  467.  
  468.         NAME
  469.  
  470.           Shuffle -- Randomize an array containing CardIDs.
  471.  
  472.         SYNOPSIS
  473.  
  474.           Shuffle( where, count, offset );
  475.  
  476.           void Shuffle( CardID_t *, UWORD, UWORD );
  477.  
  478.         FUNCTION
  479.  
  480.           Randomly reorder an array of count CardIDs.  This function uses
  481.           the amiga.lib function RangeRand() which uses RangeSeed as its
  482.           seed value.  To get different results each time you run your
  483.           program, you need to set different seed values.
  484.  
  485.         INPUTS
  486.  
  487.           where     A pointer to the first CardID_t.
  488.           count     The number of CardID_t's to reorder.
  489.           offset    The number of bytes from one CardID_t to the next.
  490.  
  491.         RESULT
  492.  
  493.           none
  494.  
  495.         EXAMPLE
  496.  
  497.           extern ULONG __far RangeSeed;  /* Remove "__far" for Aztec C */
  498.           CardID_t where[52];
  499.  
  500.           /* First, seed RangeRand() seed value RangeSeed. */
  501.           CurrentTime( &RangeSeed, &RangeSeed );
  502.  
  503.           /* Now fill a new deck starting with Hearts, then shuffle it. */
  504.           if ( CardRange( where, 52, sizeof(CardID_t), SUIT_HEARTS, 1 ) )
  505.              Shuffle( where, 52, sizeof(CardID_t) );
  506.  
  507.         NOTES
  508.  
  509.         BUGS
  510.  
  511.         SEE ALSO
  512.  
  513.           CardRange()
  514.  
  515.  
  516.  
  517.  
  518.  
  519.  
  520.  
  521.  
  522.  
  523.  
  524.  
  525.  
  526.                       * * * * * * * * * * * * * * * * * * * * * *
  527.  
  528.  
  529.  
  530.  
  531.         TML's C Language Card Image Package v1.3               Page 9 of 9
  532.  
  533.  
  534.         NAME
  535.  
  536.           ValidCardID -- Test validity of a CardID
  537.  
  538.         SYNOPSIS
  539.  
  540.           success = ValidCardID( CardID );
  541.  
  542.           BOOL ValidCardID( CardID_t );
  543.  
  544.         FUNCTION
  545.  
  546.           Determine whether a CardID has a value which represents one of
  547.           the cards in the card package.
  548.  
  549.         INPUTS
  550.  
  551.           CardID    Some value which might represent a card.
  552.  
  553.         RESULT
  554.  
  555.           success = TRUE if CardID represents a valid card, FALSE
  556.           otherwise.
  557.  
  558.         EXAMPLE
  559.  
  560.         NOTES
  561.  
  562.         BUGS
  563.  
  564.         SEE ALSO
  565.  
  566.           CardID(), CardSuit(), CardRank()
  567.  
  568.  
  569.  
  570.  
  571.  
  572.  
  573.  
  574.  
  575.  
  576.  
  577.  
  578.  
  579.  
  580.  
  581.  
  582.  
  583.  
  584.  
  585.  
  586.  
  587.  
  588.  
  589.  
  590.  
  591.  
  592.                       * * * * * * * * * * * * * * * * * * * * * *
  593.  
  594.  
  595.  
  596.